/*
 * Copyright 1996-2006 Sun Microsystems, Inc.  All Rights Reserved.
 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
 *
 * This code is free software; you can redistribute it and/or modify it
 * under the terms of the GNU General Public License version 2 only, as
 * published by the Free Software Foundation.  Sun designates this
 * particular file as subject to the "Classpath" exception as provided
 * by Sun in the LICENSE file that accompanied this code.
 *
 * This code is distributed in the hope that it will be useful, but WITHOUT
 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
 * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
 * version 2 for more details (a copy is included in the LICENSE file that
 * accompanied this code).
 *
 * You should have received a copy of the GNU General Public License version
 * 2 along with this work; if not, write to the Free Software Foundation,
 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
 *
 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
 * CA 95054 USA or visit www.sun.com if you need additional information or
 * have any questions.
 */

package org.loon.framework.android.game.core.graphics.geom;

/**
 * The <code>Shape</code> interface provides definitions for objects that
 * represent some form of geometric shape. The <code>Shape</code> is described
 * by a {@link PathIterator} object, which can express the outline of the
 * <code>Shape</code> as well as a rule for determining how the outline divides
 * the 2D plane into interior and exterior points. Each <code>Shape</code>
 * object provides callbacks to get the bounding box of the geometry, determine
 * whether points or rectangles lie partly or entirely within the interior of
 * the <code>Shape</code>, and retrieve a <code>PathIterator</code> object that
 * describes the trajectory path of the <code>Shape</code> outline.
 * <p>
 * <b>Definition of insideness:</b> A point is considered to lie inside a
 * <code>Shape</code> if and only if:
 * <ul>
 * <li>it lies completely inside the<code>Shape</code> boundary <i>or</i>
 * <li>
 * it lies exactly on the <code>Shape</code> boundary <i>and</i> the space
 * immediately adjacent to the point in the increasing <code>X</code> direction
 * is entirely inside the boundary <i>or</i>
 * <li>
 * it lies exactly on a horizontal boundary segment <b>and</b> the space
 * immediately adjacent to the point in the increasing <code>Y</code> direction
 * is inside the boundary.
 * </ul>
 * <p>
 * The <code>contains</code> and <code>intersects</code> methods consider the
 * interior of a <code>Shape</code> to be the area it encloses as if it were
 * filled. This means that these methods consider unclosed shapes to be
 * implicitly closed for the purpose of determining if a shape contains or
 * intersects a rectangle or if a shape contains a point.
 * 
 * @see and.awt.geom.PathIterator
 * @see and.awt.geom.AffineTransform
 * @see and.awt.geom.FlatteningPathIterator
 * @see and.awt.geom.GeneralPath
 * 
 * @author Jim Graham
 * @since 1.2
 */
public interface Shape {
	/**
	 * Returns an integer {@link Rectangle} that completely encloses the
	 * <code>Shape</code>. Note that there is no guarantee that the returned
	 * <code>Rectangle</code> is the smallest bounding box that encloses the
	 * <code>Shape</code>, only that the <code>Shape</code> lies entirely within
	 * the indicated <code>Rectangle</code>. The returned <code>Rectangle</code>
	 * might also fail to completely enclose the <code>Shape</code> if the
	 * <code>Shape</code> overflows the limited range of the integer data type.
	 * The <code>getBounds2D</code> method generally returns a tighter bounding
	 * box due to its greater flexibility in representation.
	 * 
	 * @return an integer <code>Rectangle</code> that completely encloses the
	 *         <code>Shape</code>.
	 * @see #getBounds2D
	 * @since 1.2
	 */
	public Rectangle getBounds();

	/**
	 * Returns a high precision and more accurate bounding box of the
	 * <code>Shape</code> than the <code>getBounds</code> method. Note that
	 * there is no guarantee that the returned {@link Rectangle2D} is the
	 * smallest bounding box that encloses the <code>Shape</code>, only that the
	 * <code>Shape</code> lies entirely within the indicated
	 * <code>Rectangle2D</code>. The bounding box returned by this method is
	 * usually tighter than that returned by the <code>getBounds</code> method
	 * and never fails due to overflow problems since the return value can be an
	 * instance of the <code>Rectangle2D</code> that uses double precision
	 * values to store the dimensions.
	 * 
	 * @return an instance of <code>Rectangle2D</code> that is a high-precision
	 *         bounding box of the <code>Shape</code>.
	 * @see #getBounds
	 * @since 1.2
	 */
	public Rectangle2D getBounds2D();

	/**
	 * Tests if the specified coordinates are inside the boundary of the
	 * <code>Shape</code>.
	 * 
	 * @param x
	 *            the specified X coordinate to be tested
	 * @param y
	 *            the specified Y coordinate to be tested
	 * @return <code>true</code> if the specified coordinates are inside the
	 *         <code>Shape</code> boundary; <code>false</code> otherwise.
	 * @since 1.2
	 */
	public boolean contains(double x, double y);

	/**
	 * Tests if a specified {@link Point2D} is inside the boundary of the
	 * <code>Shape</code>.
	 * 
	 * @param p
	 *            the specified <code>Point2D</code> to be tested
	 * @return <code>true</code> if the specified <code>Point2D</code> is inside
	 *         the boundary of the <code>Shape</code>; <code>false</code>
	 *         otherwise.
	 * @since 1.2
	 */
	public boolean contains(Point2D p);

	/**
	 * Tests if the interior of the <code>Shape</code> intersects the interior
	 * of a specified rectangular area. The rectangular area is considered to
	 * intersect the <code>Shape</code> if any point is contained in both the
	 * interior of the <code>Shape</code> and the specified rectangular area.
	 * <p>
	 * The {@code Shape.intersects()} method allows a {@code Shape}
	 * implementation to conservatively return {@code true} when:
	 * <ul>
	 * <li>
	 * there is a high probability that the rectangular area and the
	 * <code>Shape</code> intersect, but
	 * <li>
	 * the calculations to accurately determine this intersection are
	 * prohibitively expensive.
	 * </ul>
	 * This means that for some {@code Shapes} this method might return {@code
	 * true} even though the rectangular area does not intersect the {@code
	 * Shape}. The {@link and.awt.geom.Area Area} class performs more accurate
	 * computations of geometric intersection than most {@code Shape} objects
	 * and therefore can be used if a more precise answer is required.
	 * 
	 * @param x
	 *            the X coordinate of the upper-left corner of the specified
	 *            rectangular area
	 * @param y
	 *            the Y coordinate of the upper-left corner of the specified
	 *            rectangular area
	 * @param w
	 *            the width of the specified rectangular area
	 * @param h
	 *            the height of the specified rectangular area
	 * @return <code>true</code> if the interior of the <code>Shape</code> and
	 *         the interior of the rectangular area intersect, or are both
	 *         highly likely to intersect and intersection calculations would be
	 *         too expensive to perform; <code>false</code> otherwise.
	 * @see and.awt.geom.Area
	 * @since 1.2
	 */
	public boolean intersects(double x, double y, double w, double h);

	/**
	 * Tests if the interior of the <code>Shape</code> intersects the interior
	 * of a specified <code>Rectangle2D</code>. The {@code Shape.intersects()}
	 * method allows a {@code Shape} implementation to conservatively return
	 * {@code true} when:
	 * <ul>
	 * <li>
	 * there is a high probability that the <code>Rectangle2D</code> and the
	 * <code>Shape</code> intersect, but
	 * <li>
	 * the calculations to accurately determine this intersection are
	 * prohibitively expensive.
	 * </ul>
	 * This means that for some {@code Shapes} this method might return {@code
	 * true} even though the {@code Rectangle2D} does not intersect the {@code
	 * Shape}. The {@link and.awt.geom.Area Area} class performs more accurate
	 * computations of geometric intersection than most {@code Shape} objects
	 * and therefore can be used if a more precise answer is required.
	 * 
	 * @param r
	 *            the specified <code>Rectangle2D</code>
	 * @return <code>true</code> if the interior of the <code>Shape</code> and
	 *         the interior of the specified <code>Rectangle2D</code> intersect,
	 *         or are both highly likely to intersect and intersection
	 *         calculations would be too expensive to perform;
	 *         <code>false</code> otherwise.
	 * @see #intersects(double, double, double, double)
	 * @since 1.2
	 */
	public boolean intersects(Rectangle2D r);

	/**
	 * Tests if the interior of the <code>Shape</code> entirely contains the
	 * specified rectangular area. All coordinates that lie inside the
	 * rectangular area must lie within the <code>Shape</code> for the entire
	 * rectanglar area to be considered contained within the <code>Shape</code>.
	 * <p>
	 * The {@code Shape.contains()} method allows a {@code Shape} implementation
	 * to conservatively return {@code false} when:
	 * <ul>
	 * <li>
	 * the <code>intersect</code> method returns <code>true</code> and
	 * <li>
	 * the calculations to determine whether or not the <code>Shape</code>
	 * entirely contains the rectangular area are prohibitively expensive.
	 * </ul>
	 * This means that for some {@code Shapes} this method might return {@code
	 * false} even though the {@code Shape} contains the rectangular area. The
	 * {@link and.awt.geom.Area Area} class performs more accurate geometric
	 * computations than most {@code Shape} objects and therefore can be used if
	 * a more precise answer is required.
	 * 
	 * @param x
	 *            the X coordinate of the upper-left corner of the specified
	 *            rectangular area
	 * @param y
	 *            the Y coordinate of the upper-left corner of the specified
	 *            rectangular area
	 * @param w
	 *            the width of the specified rectangular area
	 * @param h
	 *            the height of the specified rectangular area
	 * @return <code>true</code> if the interior of the <code>Shape</code>
	 *         entirely contains the specified rectangular area;
	 *         <code>false</code> otherwise or, if the <code>Shape</code>
	 *         contains the rectangular area and the <code>intersects</code>
	 *         method returns <code>true</code> and the containment calculations
	 *         would be too expensive to perform.
	 * @see and.awt.geom.Area
	 * @see #intersects
	 * @since 1.2
	 */
	public boolean contains(double x, double y, double w, double h);

	/**
	 * Tests if the interior of the <code>Shape</code> entirely contains the
	 * specified <code>Rectangle2D</code>. The {@code Shape.contains()} method
	 * allows a {@code Shape} implementation to conservatively return {@code
	 * false} when:
	 * <ul>
	 * <li>
	 * the <code>intersect</code> method returns <code>true</code> and
	 * <li>
	 * the calculations to determine whether or not the <code>Shape</code>
	 * entirely contains the <code>Rectangle2D</code> are prohibitively
	 * expensive.
	 * </ul>
	 * This means that for some {@code Shapes} this method might return {@code
	 * false} even though the {@code Shape} contains the {@code Rectangle2D}.
	 * The {@link and.awt.geom.Area Area} class performs more accurate geometric
	 * computations than most {@code Shape} objects and therefore can be used if
	 * a more precise answer is required.
	 * 
	 * @param r
	 *            The specified <code>Rectangle2D</code>
	 * @return <code>true</code> if the interior of the <code>Shape</code>
	 *         entirely contains the <code>Rectangle2D</code>;
	 *         <code>false</code> otherwise or, if the <code>Shape</code>
	 *         contains the <code>Rectangle2D</code> and the
	 *         <code>intersects</code> method returns <code>true</code> and the
	 *         containment calculations would be too expensive to perform.
	 * @see #contains(double, double, double, double)
	 * @since 1.2
	 */
	public boolean contains(Rectangle2D r);

	/**
	 * Returns an iterator object that iterates along the <code>Shape</code>
	 * boundary and provides access to the geometry of the <code>Shape</code>
	 * outline. If an optional {@link AffineTransform} is specified, the
	 * coordinates returned in the iteration are transformed accordingly.
	 * <p>
	 * Each call to this method returns a fresh <code>PathIterator</code> object
	 * that traverses the geometry of the <code>Shape</code> object
	 * independently from any other <code>PathIterator</code> objects in use at
	 * the same time.
	 * <p>
	 * It is recommended, but not guaranteed, that objects implementing the
	 * <code>Shape</code> interface isolate iterations that are in process from
	 * any changes that might occur to the original object's geometry during
	 * such iterations.
	 * 
	 * @param at
	 *            an optional <code>AffineTransform</code> to be applied to the
	 *            coordinates as they are returned in the iteration, or
	 *            <code>null</code> if untransformed coordinates are desired
	 * @return a new <code>PathIterator</code> object, which independently
	 *         traverses the geometry of the <code>Shape</code>.
	 * @since 1.2
	 */
	public PathIterator getPathIterator(AffineTransform at);

	/**
	 * Returns an iterator object that iterates along the <code>Shape</code>
	 * boundary and provides access to a flattened view of the
	 * <code>Shape</code> outline geometry.
	 * <p>
	 * Only SEG_MOVETO, SEG_LINETO, and SEG_CLOSE point types are returned by
	 * the iterator.
	 * <p>
	 * If an optional <code>AffineTransform</code> is specified, the coordinates
	 * returned in the iteration are transformed accordingly.
	 * <p>
	 * The amount of subdivision of the curved segments is controlled by the
	 * <code>flatness</code> parameter, which specifies the maximum distance
	 * that any point on the unflattened transformed curve can deviate from the
	 * returned flattened path segments. Note that a limit on the accuracy of
	 * the flattened path might be silently imposed, causing very small
	 * flattening parameters to be treated as larger values. This limit, if
	 * there is one, is defined by the particular implementation that is used.
	 * <p>
	 * Each call to this method returns a fresh <code>PathIterator</code> object
	 * that traverses the <code>Shape</code> object geometry independently from
	 * any other <code>PathIterator</code> objects in use at the same time.
	 * <p>
	 * It is recommended, but not guaranteed, that objects implementing the
	 * <code>Shape</code> interface isolate iterations that are in process from
	 * any changes that might occur to the original object's geometry during
	 * such iterations.
	 * 
	 * @param at
	 *            an optional <code>AffineTransform</code> to be applied to the
	 *            coordinates as they are returned in the iteration, or
	 *            <code>null</code> if untransformed coordinates are desired
	 * @param flatness
	 *            the maximum distance that the line segments used to
	 *            approximate the curved segments are allowed to deviate from
	 *            any point on the original curve
	 * @return a new <code>PathIterator</code> that independently traverses a
	 *         flattened view of the geometry of the <code>Shape</code>.
	 * @since 1.2
	 */
	public PathIterator getPathIterator(AffineTransform at, double flatness);
}
